refundCapturedReservation

HTTP method: POST

https://testgateway.altapaysecure.com/merchant/API/refundCapturedReservation

Use the refundCapturedReservation method to refund a previously captured reservation. You can make a partial refund, a full refund, or, in some cases, an over refund.

Not all payments can be refunded, and some can be refunded multiple times, depending on the payment method and the acquirer.

For information about Klarna KP refunds, see Refund a Klarna payment.

Select a payment method to see the parameters relevant for that method:

Request parameters

Parameter	Description	Type	Mandatory	Notes
transaction_id	The id of a specific payment.	[0-9a-f]{1,32}	X
amount	The amount to refund to your customer. The amount must be greater than zero, but less than or equal to the amount captured in the payment. If you do not set an amount, the full amount is refunded.	float
reconciliation_identifier	This parameter can only be used when the type parameter is set to paymentAndCapture.This is the sales reconciliation identifier, used in the reconciliation CSV files you can download from the Merchant Interface, or by using the getCustomReport method. For more information, see getCustomReport.	String{0,100}
allow_over_refund	To enable refund of an amount greater than the captured amount, set allow_over_refund to 1. Not all providers support this.	1 or 0
invoice_number	The invoice number as it appears on the invoice.	String		Only for Arvato (PayByBill)
orderLines	The total amount of all order lines must be equal to the refund amount parameter.	Array	X	If you do a partial refund on an invoice payment, you must include the orderLines array. It is however, recommended to always send order lines

For each order line:

Value	Description	Type	Mandatory
description	Description of an item.	String (255)	Yes
itemId	The item identification. Each itemId must be unique within an order.	String (100)	Yes
quantity	The quantity of the item. The value must be greater than zero.	Decimal	Yes
unitPrice	The unit price, excluding sales tax. The value must be greater than zero, unless the optional goodsType parameter is set to handling, in which case the field can be used to provide a discount.	Decimal	Yes
taxPercent	This is the tax percentage of the unit price. Send both the taxPercent and taxAmount parameters in the method call. If you provide only one, the other is inferred, and rounding errors may occur. The taxAmount is used for the calculation, and taxPercent is printed on the invoice.	Decimal	No
taxAmount	This is the total tax on an order line, before any discounts are applied. It is recommended to use taxAmount if possible. If you provide both taxPercent and taxAmount, the amount takes precedence. Send both the taxPercent and taxAmount parameters in the method call. If you provide only one of the taxPercent and taxAmount parameters, the other parameter is inferred, and rounding errors may occur. The taxAmount is used for the calculation, and taxPercent is printed on the invoice.	Decimal	Yes
unitCode	The relevant measurement unit for the order line. For example, kg.	String (50)
discount	The order line's discount in percent.	Decimal
goodsType	The goods type of the order line - shipment \| handling \| item \| digital \| discount \| gift_card \| physical \| sales_tax
imageUrl	The full URL of the icon for the item	String (255)
productUrl	The full URL for the description of the item	String (255)

Response parameters

The table shows the most pertinent response values for the method. For a complete list of API response parameters, see API Response structure (XML).

Parameter	Description	Type
RefundAmount	The amount refunded to the card holder.	float
RefundCurrency	The 3 digit currency code.	string
Result	Success, Open or Fail.	string
RefundResult	Success, Open or Fail.	string

Examples

Basic request

curl --request POST \
  --url https://<YourShopName>.altapaysecure.com/merchant/API/refundCapturedReservation \
  --header 'Authorization: Basic auth' \
  --data transaction_id=12345 \
  --data amount=14.20 \

Request with order lines

curl --request POST \
  --url https://<YourShopName>.altapaysecure.com/merchant/API/refundCapturedReservation \
  --header 'Authorization: Basic auth' \
  --data transaction_id=12345 \
  --data amount=14.20 \
  --data orderLines[0][description]='White sugar' \
  --data orderLines[0][itemId]=productid \
  --data orderLines[0][quantity]=1.5 \
  --data orderLines[0][taxPercent]=20 \
  --data orderLines[0][unitCode]=kg \
  --data orderLines[0][unitPrice]=5.75 \
  --data orderLines[1][description]='Brown sugar' \
  --data orderLines[1][itemId]=productid2 \
  --data orderLines[1][quantity]=2.5 \
  --data orderLines[1][taxPercent]=20 \
  --data orderLines[1][unitCode]=kg \
  --data orderLines[1][unitPrice]=8.75 \

XML response

<?xml version="1.0" encoding="utf-8" ?>
<APIResponse version="20170228">
	<Header>
		<Date>2020-09-29T12:34:56+02:00</Date>
		<Path>API/refundCapturedReservation</Path>
		<ErrorCode>0</ErrorCode>
		<ErrorMessage></ErrorMessage>
	</Header>
	<Body>
		<RefundAmount>0.12</RefundAmount>
		<RefundCurrency>978</RefundCurrency>
		<Result>Success</Result>
		<RefundResult>Success</RefundResult> <!-- deprecated -->
		<Transactions>
			<Transaction>
				<TransactionId>1</TransactionId>
				<PaymentId>ccc1479c-37f9-4962-8d2c-662d75117e9d</PaymentId>
				<AuthType>payment</AuthType>
				<CardStatus>Valid</CardStatus>
				<CreditCardExpiry>
					<Year>2028</Year>
					<Month>08</Month>
				</CreditCardExpiry>
				<CreditCardToken>93f534a2f5d66d6ab3f16c8a7bb7e852656d4bb2</CreditCardToken>
				<CreditCardMaskedPan>411111******1111</CreditCardMaskedPan>
				<CardInformation>
					<IsTokenized>false</IsTokenized>
					<Token>hYKu5yO33OsWYfT7g4weghvPjBnb3YEZYDysb7NzAf/sHk7j5j5ejzfF2ZyhLyggcCgaNKEmjg==+1</Token>
					<MaskedPan>411111******1111</MaskedPan>
					<Expiry>
						<Year>2028</Year>
						<Month>08</Month>
					</Expiry>
					<IssuingCountry>DK</IssuingCountry>
					<LastFourDigits>1111</LastFourDigits>
					<Scheme>VISA</Scheme>
				</CardInformation>
				<ThreeDSecureResult>Not_Applicable</ThreeDSecureResult>
				<InvoiceOrderInfo />
				<LiableForChargeback>Merchant</LiableForChargeback>
				<BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e</BlacklistToken>
				<ShopOrderId>myorderid</ShopOrderId>
				<Shop>AltaPay Shop</Shop>
				<Terminal>AltaPay Test Terminal</Terminal>
				<TransactionStatus>refunded</TransactionStatus>
				<ReasonCode>NONE</ReasonCode>
				<MerchantCurrency>978</MerchantCurrency>
				<MerchantCurrencyAlpha>EUR</MerchantCurrencyAlpha>
				<CardHolderCurrency>978</CardHolderCurrency>
				<CardHolderCurrencyAlpha>EUR</CardHolderCurrencyAlpha>
				<ReservedAmount>1.00</ReservedAmount>
				<CapturedAmount>1.00</CapturedAmount>
				<RefundedAmount>0.12</RefundedAmount>
				<RecurringDefaultAmount>0</RecurringDefaultAmount>
				<CreatedDate>2010-09-28 11:34:56</CreatedDate>
				<UpdatedDate>2010-09-28 13:00:00</UpdatedDate>
				<PaymentNature>CreditCard</PaymentNature>
				<PaymentNatureService name="TestAcquirer">
					<SupportsRefunds>true</SupportsRefunds>
					<SupportsRelease>true</SupportsRelease>
					<SupportsMultipleCaptures>true</SupportsMultipleCaptures>
					<SupportsMultipleRefunds>false</SupportsMultipleRefunds>
				</PaymentNatureService>
				<FraudRiskScore>13.37</FraudRiskScore>
				<FraudExplanation>Fraud detection explanation</FraudExplanation>
				<PaymentInfos>
					<PaymentInfo name="Form_Created_At">2010-09-28 12:34:56</PaymentInfo>
					<PaymentInfo name="Form_Provider">AltaPay Test Form</PaymentInfo>
					<PaymentInfo name="Merchant_Provided_Info">Some info by merchant</PaymentInfo>
				</PaymentInfos>
				<CustomerInfo>
					<UserAgent>Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.41 Safari/535.7</UserAgent>
					<IpAddress>127.127.127.127</IpAddress>
					<Email>support@altapay.com</Email>
					<Username>support</Username>
					<CustomerPhone>+45 7020 0056</CustomerPhone>
					<OrganisationNumber>12345678</OrganisationNumber>
					<CountryOfOrigin>
						<Country>DK</Country>
					<Source>BillingAddress</Source>
					</CountryOfOrigin>
					<BillingAddress>
						<Firstname>Palle</Firstname>
						<Lastname>Simonsen</Lastname>
						<Address>Rosenkæret 13</Address>
						<City>Søborg</City>
						<PostalCode>2860</PostalCode>
						<Country>DK</Country>
					</BillingAddress>
					<ShippingAddress/>
					<RegisteredAddress/>
				</CustomerInfo>
				<ReconciliationIdentifiers>
					<ReconciliationIdentifier>
						<Id>f4e2533e-c578-4383-b075-bc8a6866784a</Id>
						<Amount currency="978">1.00</Amount>
						<Type>captured</Type>
						<Date>2020-09-28T12:00:00+02:00</Date>
					</ReconciliationIdentifier>
					<ReconciliationIdentifier>
						<Id>8774bcef-7549-4497-948e-82280ca69f80</Id>
						<Amount currency="978">0.12</Amount>
						<Type>refunded</Type>
						<Date>2020-09-28T13:00:00+02:00</Date>
					</ReconciliationIdentifier>
				</ReconciliationIdentifiers>
			</Transaction>
		</Transactions>
	</Body>
</APIResponse>

Test case data

Use the following to test credit card transactions.

Scenario	Error type	Amount	Card Number
Fails at refundCapturedReservation	Failed	9.66	Pattern: ????????????0966 Visa: 4160000000000966 MasterCard: 5530000000000966
Fails at refundCapturedReservation	Error	9.67	Pattern: ????????????0967 Visa: 4110000000000967 MasterCard: 5570000000000967